home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kcmodulecontainer.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  6.4 KB  |  208 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (C) 2004 Frans Englich <frans.englich@telia.com>
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License as published by the Free Software Foundation; either
  7.     version 2 of the License, or (at your option) any later version.
  8.  
  9.     This library is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     Library General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.     Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef KCMODULECONTAINER_H
  21. #define KCMODULECONTAINER_H
  22.  
  23. #include <qvaluelist.h>
  24. #include <qstring.h>
  25. #include <qstringlist.h>
  26.  
  27. #include <kcmodule.h>
  28. #include <kcmoduleloader.h>
  29.  
  30. class QTabWidget;
  31. class QWidget;
  32. class QVBoxLayout;
  33.  
  34. class KCModuleProxy;
  35.  
  36. /**
  37.  * @ingroup kcmodule
  38.  * @brief KCModuleContainer is a convenience class encapsulating several KCModules.
  39.  *
  40.  * The KCModuleContainer class is a convenience class for organizing a multiple set
  41.  * of KCModule. KCModuleContainer is a sub class of KCModule and builds an interface mainly
  42.  * consisting of a tab widget where each tab contains one of the modules specified via one of the
  43.  * constructors. KCModuleContainer can handle modules which requires root permissions. What you
  44.  * most likely want is the KCMODULECONTAINER macro. \n
  45.  * Sometimes it is of interest to detect in runtime whether a module should be loaded or not. This
  46.  * can be achieved by sub classing KCModuleContainer, doing the probing/testing checks and then manually
  47.  * call addModule for each module which should be displayed. When all calls to addModule is done, call
  48.  * finalize() which performs some necessary final steps.
  49.  *
  50.  * @author Frans Englich <frans.englich@telia.com>
  51.  * @since 3.4
  52.  */
  53. class KUTILS_EXPORT KCModuleContainer : public KCModule
  54. {
  55.     Q_OBJECT
  56.     public:
  57.         /**
  58.          * Creates a KCModuleContainer with tabs, each one containing one of the
  59.          * specified modules in @p mods.
  60.          *
  61.                  * @param parent the parent QWidget.
  62.                  * @param name the module's name.
  63.          * @param mods The list of KCModules to be loaded. The name of each
  64.          * KCModule is its service name, that is the name of the desktop file without
  65.          * the ".desktop" part
  66.          *
  67.          */
  68.         KCModuleContainer( QWidget* parent, const char* name, const QStringList& mods );
  69.  
  70.         /**
  71.          * This is a convenience function, instead of building a QStringList you
  72.          * can specify the modules in a comma separated QString. For example;
  73.          * \code
  74.          * KCModuleContainer* cont = KCModuleContainer( this, "kcm_misc", QString("kcm_energy, kcm_keyboard ,kcm_useraccount, kcm_mouse") );
  75.          * \endcode
  76.          * The other constructor takes its modules in a QStringlist which also can be constructed from a
  77.          * string and thus you will have to be explicit on the data type.
  78.          *
  79.          * What you probably want is the KCMODULECONTAINER macro which builds an KCModule
  80.          * for you, taking the modules you want as argument.
  81.          *
  82.          * @param parent The parent widget
  83.          * @param name The service name
  84.          * @param mods The modules to load
  85.          * @return The KCModule containing the requested modules.
  86.          */
  87.         KCModuleContainer( QWidget *parent, const char* name, const QString& mods = QString() );
  88.  
  89.         /**
  90.          * Adds the specified module to the tab widget. Setting the tab icon, text,
  91.          * tool tip, connecting the signals is what it does.
  92.          *
  93.          * @param module the name of the module to add. The name is the desktop file's name
  94.          * without the ".desktop" part.
  95.          */
  96.         void addModule( const QString& module );
  97.  
  98.         /**
  99.          * Default destructor.
  100.          */
  101.         virtual ~KCModuleContainer();
  102.  
  103.         /**
  104.          * Reimplemented for internal purposes.
  105.          * @internal
  106.          */
  107.         void save();
  108.  
  109.         /**
  110.          * Reimplemented for internal purposes.
  111.          * @internal
  112.          */
  113.         void load();
  114.  
  115.         /**
  116.          * Reimplemented for internal purposes.
  117.          * @internal
  118.          */
  119.         void defaults();
  120.  
  121.     protected:
  122.  
  123.         /**
  124.          * Sets this KCM's buttons and adds a AdminMode button
  125.          * if necessary. If KCModuleContainer is subclassed finalize()
  126.          * should be called in the constructor after all calls to addModule
  127.          * have been done. Call it once.
  128.          */
  129.         void finalize();
  130.  
  131.         typedef QValueList<KCModuleProxy*> ModuleList;
  132.  
  133.         /**
  134.          * A list containing KCModuleProxy objects which
  135.          * have changed and must be saved.
  136.          */
  137.         ModuleList changedModules;
  138.  
  139.         /**
  140.          * A list of all modules which are encapsulated.
  141.          */
  142.         ModuleList allModules; // KDE 4 put in the Private class and abstract with getter
  143.  
  144.     private slots:
  145.  
  146.         /**
  147.          * Enables/disables the Admin Mode button, as appropriate.
  148.          */
  149.         void tabSwitched( QWidget * module );
  150.  
  151.         void moduleChanged(KCModuleProxy *proxy);
  152.  
  153.         /**
  154.          * Called when the user clicks our custom root button.
  155.          */
  156.         void runAsRoot();
  157.  
  158.         /**
  159.          * Enables the admin mode button
  160.          */
  161.         void rootExited();
  162.  
  163.     private:
  164.  
  165.         void init();
  166.  
  167.         class KCModuleContainerPrivate;
  168.         KCModuleContainerPrivate *d;
  169.  
  170. };
  171.  
  172. /**
  173.  * @ingroup kcmodule
  174.  * This macro creates an factory declaration which when run creates an KCModule with specified
  175.  * modules. For example:
  176.  * \code
  177.  * KCMODULECONTAINER( "kcm_fonts, kcm_keyboard,kcm_fonts", misc_modules)
  178.  * \endcode
  179.  * would create a KCModule with three tabs, each containing one of the specified KCMs. Each
  180.  * use of the macro must be accompanied by a desktop file where the factory name equals
  181.  * the second argument in the macro(in this example, misc_modules). \n
  182.  * The module container takes care of testing the contained modules when being shown, as well
  183.  * as when the module itself is asked whether it should be shown.
  184.  *
  185.  * @param modules the modules to put in the container
  186.  * @param factoryName what factory name the module should have
  187.  */
  188. #define KCMODULECONTAINER( modules, factoryName ) \
  189. extern "C" \
  190. { \
  191.     KCModule *create_## factoryName(QWidget *parent, const char *name) \
  192.     { \
  193.         return new KCModuleContainer( parent, name, QString( modules ) ); \
  194.     } \
  195.     \
  196.     bool test_## factoryName() \
  197.     { \
  198.         QStringList modList = QStringList::split( ",", QString(modules).remove( " " )); \
  199.         for ( QStringList::Iterator it = modList.begin(); it != modList.end(); ++it ) \
  200.             if ( KCModuleLoader::testModule( *it ) ) \
  201.                 return true; \
  202.         return false; \
  203.     } \
  204. }
  205.  
  206. #endif // KCMODULECONTAINER_H
  207.  
  208.